{smcl}
{* 2014-09-02 scott long & jeremy freese}{...}
{title:Title}

{p2colset 5 13 24 2}{...}
{p2col:{cmd:mgen} {hline 2}}Generate variables for plotting with predictions
from {cmd:margins}{p_end}
{p2colreset}{...}


{title:General syntax}

{p 4 8 2}
{cmd:mgen} [{it:if}] [{it:in}]{cmd:,}
 [mgen-options] [margins-options]

{marker overview}
{title:Overview}

{pstd}
{cmd:mgen} uses results from {cmd:margins} to create variables for plots.
{cmd:mgen} has the advantage of allowing marginal effects from multiple models to be combined in the same plot, and for marginal effects from multiple categories to be combined in the same plot.

{title:Options}

    {help mgen##margins:Options for margins}
    {help mgen##name:Naming variables}
    {help mgen##stats:Statistics and values generated}
    {help mgen##meanpred:Variables generate with the meanpred option}
    {help mgen##model:How mgen works with various types of models}
    {help mgen##other:Miscellaneous options}
    {help mgen##return:Returns}
    {help mgen##examples:Examples}

{marker margins}
{dlgtab:Options for margins}
{p2colset 7 24 25 0}
{p 6 6 2}
Most options from {cmd:margins} can be used.


{synopt:{opt at(atspec)}}
Specify the values of regressors for which predictions are calculated.
For example, {cmd:at(age=(20(5)85)}.
For details, see {help margins##at_op:at(atspec)}.

{synopt:{opt atmeans}}
All regressors not specified with {cmd:at()} are held at their means.
If {cmd:if} or {cmd:in} are used to specify the sample, the means are
computed for the selected observations. If {cmd:atmeans} is not specified,
marginal effects are averaged across observations.

{synopt:{opt dydx(covariate)}}
Computes marginal effects of one covariate.
The type of marginal effect computed depends on the factor variable notation
included in the regression model.
By default, a marginal change is computed for variables
with no factor variable notation and variables with the {cmd:c.} prefix.
Discrete changes between categories are computed for
variables with the {cmd:i.} prefix. See {helpb fvvarlist:factor variable notation} for
more information.

{p 6 6 2}
{it:if} or {it:in} conditions select the observations
used by {cmd:margins}.
With {cmd:atmeans}, the means are computed conditionally
on the {it:if} or {it:in} conditions. If {cmd:atmeans} is not used, the
average prediction is the average for the sample selected by the
{it:if} or {it:in} conditions. These conditions are {it:not} used to
restrict the sample when the {cmd:meandpred} is specified (i.e., the
average prediction is the average over the entire sample).

{marker name}
{dlgtab:Naming and summarizing variables}
{p2colset 9 30 31 0}
{p 6 6 2}
Variables that are generated have names of the form:

{p 8 6 2}
{it:<stubname><quantity><category>}.

{p 6 6 2}
{it:<stubname>} is common to all variables.
{it:<quantity>} describes the {help mgen##stats:content} contained in
the variable
(e.g., {bf:se} indicates a standard error).
{it:<category>} is the value or the value label of the outcome category;
for some models there is no {it:<category>}.

{synopt:{opt stub(string)}}
All variables begin with {it:stubname}.
If unspecified, default is "_".
{p_end}

{synopt:{opt replace}}
If the variables to be generated already exist, they will be
replaced.
{p_end}

{synopt:{opt predn:ame(string)}}
The name used for the prediction (e.g., a probability or discrete change).
By default the name of the expression from {cmd:margins} is used.
For example, {cmd:pr} is used for predicted probabilities with
{cmd:logit}. If you want a different name, use {cmd:predname()}.
{p_end}

{synopt:{opt predl:abel(string)}}
This label is used in the variable label for the prediction.
This can be useful for labeling the variables that are being plotted.
{p_end}

{synopt:{opt nol:abel}} Do not use value labels from the outcome
variable for <category>. For example, use {bf:mystubdydx1}
rather than {bf:mystubdydxSR} where SR is the value label for
category 1 of the outcome.
{p_end}

{synopt:{opt valuel:ength(integer)}}
Set the length of value labels used to label the outcome category.
{p_end}

{marker stats}
{dlgtab:Statistics and variables generated}

{p 6 6 2}
Variables generated by {cmd:mgen} include estimates and related statistics from
{cmd:margins} and values of the regressor that is changing as specified by
{bf:at()}.
The following names are used in naming variables.

{p2colset 10 26 26 12}{...}
{p2col :<quantity>}Description{p_end}
{p2line}
{p2col :{it:predname}}Estimate such as probabilities, dydx.
By default the prediction name from {cmd:margins}
is used; optionally the name from {cmd:predname())} is used.{p_end}
{p2col :{it:atvar}}Values of the regressor; see {cmd:atvar()} below.{p_end}
{p2col :{bf:ll}}Lower-level bound of confidence interval.{p_end}
{p2col :{bf:ul}}Upper-level bound of confidence interval.{p_end}
{p2col :{bf:pval}}p-value for test estimate is 0.{p_end}
{p2col :{bf:se}}Standard error of estimate.{p_end}
{p2col :{bf:z}}z-value of test that estimate is 0.{p_end}
{p2line}
{p2colset 7 25 26 0}
{p 6 6 2}
By default, variables are generated with the estimate
and the upper and lower bounds of the confidence interval.
Other statistics can be requested with these option:

{synopt:{opt alls:tats}}
Variables with all statistics are generatged.
{p_end}

{synopt:{opt noci}}
Suppress generating variables containing bounds of confidence interval.
{p_end}

{synopt:{opt level(#)}}
Sets the level of the of confidence interval, from 10 to 99.99.
{p_end}

{synopt:{opt force}}
Forces the computation of predictions for count
models where the dependent variable has non-integer values.
{p_end}

{synopt:{opt out:comes(numlist)}}
Variables are generated for these values of the outcome for models
where {cmd:outcomes()} is an option for {cmd:predict}, such as {cmd:mlogit}.
Outcome values must be non-negative integers.
{p_end}

{synopt:{opt pr(numlist)}}
Variables are generated for these probabilities for models
where {cmd:pr()} is an option for {cmd:predict}, such as {cmd:poisson}.
Outcome values must be non-negative integers.
{p_end}

{synopt:{opt cpr(numlist)}}
Variables are generated for these conditional probabilities for models
where {cmd:pr()} is an option for {cmd:predict}.
Outcome values must be non-negative integers.
{p_end}

{synopt:{opt atv:ars(varlist)}}
By default, variables are generated only for those independent variables
that vary within {cmd:at()}.
All variables can be included by specifying _all; none by specifying _none.
{p_end}

{marker meanpred}
{dlgtab:Variables generated with meanpred}
{p2colset 9 25 26 0}
{synopt:{opt meanp:red}}
Additional variables are generated where each observation is for a
specific value of the at-variable that is changing.

{p 6 6 2}
{cmd:meanpred} can only be used for count models.
Variables are based on the observed proportions in the
estimation samples, average predictions, and the value of the outcome
being predicted (e.g., value 5 for predictions of a count 5).
Variables are created with the name {it:<stubname><quantity>}.

{p2col :<quantity>}Description{p_end}
{p2line}
{p2col :{bf:val}}Value of the outcome{p_end}
{p2col :{bf:obeq}}Observed proportion y = {it:value}{p_end}
{p2col :{bf:oble}}Observed proportion y <= {it:value}{p_end}
{p2col :{bf:preq}}Predicted proportion y = {it:value}{p_end}
{p2col :{bf:prle}}Predicted proportion y <= {it:value}{p_end}
{p2col :{bf:obpr}}Difference between observed and predicted proportions of y = {it:value}{p_end}
{p2col :{bf:cpreq}}Average predicted Pr(y={it:value} | y>0) when conditional option specified{p_end}
{p2col :{bf:cprle}}Average predicted Pr(y<={it:value} | y>0) when conditional option specified{p_end}
{p2line}

{marker model}
{dlgtab:Model types}
{p2colset 9 24 25 0}
{p 6 6 2}
{cmd:mgen} has different default behavior depending on
what options are permitted by {cmd:predict}.
For convenience, three major types of models are called {it:categorical},
{it:count}, and {it:binary} models.

{p2line}
{p2col :{bf:categorical}}{cmd:predict} allows {cmd:outcome(}{it:#}{cmd:)},
such as {cmd: mlogit}.{p_end}
{p2col :{bf:count}}{cmd:predict} allows {cmd:pr(}{it:#}{cmd:)},
such as {cmd: poisson}.{p_end}
{p2col :{bf:binary}}{cmd:predict} default is {cmd:pr}, such as {cmd: logit}.{p_end}
{p2col :{bf:other}}None of the above, such as {cmd: regress}.{p_end}
{p2line}

{p 6 6 2}
Categorical or binary models assume all outcomes
unless either {cmd:outcome()} are specified
or the marginal prediction is specified using the {cmd:margins} options
{cmd:predict()} or {cmd:expression()}.

{p 6 6 2}
Cumulative predictions are calculated for categorical and count outcomes,
unless {cmd:outcome()} is used to specify values that exclude
a subset of the lowest observed values of the outcome.

{marker other}
{dlgtab:Miscellaneous options}
{p2colset 9 24 25 0}
{synopt:{opt detail:s}}
Display output from {cmd:margins} used to estimate quantities in table.

{synopt:{opt command:s}}
Display {cmd:margins} commands used to estimate quantities in table.

{synopt:{opt brief}}By default, the non-varying values of at-variables are
listed. They are not displayed with the {cmd:brief} option.
{p_end}


{marker returns}{...}
{dlgtab:Returns}

{p2colset 7 24 25 0}
{p 6 6 2}
{cmd:r(ifin)} is a local macro containing the if and in conditions used for predictions.

{p 6 6 2}
{cmd:r(newvars)} is a local macro containing a list of new variables that were generated.


{marker examples}
{dlgtab:Examples}
{p2colset 7 24 25 0}
{p 6 6 2}

{pstd}
{ul:{bf:Example 1: Computing probabilities for a binary outcome}}{p_end}

{phang2}{cmd:. spex logit}{p_end}
{phang2}{cmd:. mgen, at(lwg=(-2(.5)3)) stub(prlfp)}{p_end}
{phang2}{cmd:. twoway connected prlfppr1 prlfplwg}{p_end}

{pstd}
{ul:{bf:Example 2: Plotting cumulative probabilities for an ordinal outcome}}{p_end}

{phang2}{cmd:. spex ologit}{p_end}
{phang2}{cmd:. mgen, at(age = (20(5)85) year=3 white=1) stub(prclass)}{p_end}
{phang2}{cmd:. twoway connected prclassCpr1 prclassCpr2 prclassCpr3 }{p_end}
{phang2}{cmd:> prclassCpr4 prclassage}{p_end}

{pstd}
{ul:{bf:Example 3: Plotting variables from multiple mgen commands}}{p_end}

{phang2}{cmd:. spex logit}{p_end}
{phang2}{cmd:. mgen, at(inc=(0(5)95) wc=0) stub(wc0)}{p_end}
{phang2}{cmd:. mgen, at(inc=(0(5)95) wc=1) stub(wc1)}{p_end}
{phang2}{cmd:. twoway connected wc0pr1 wc1pr1 wc0inc}{p_end}

INCLUDE help spost13_footer
